home *** CD-ROM | disk | FTP | other *** search
/ The World of Computer Software / The World of Computer Software.iso / lspsql.zip / LISPSQL.DOC < prev    next >
Lisp/Scheme  |  1992-08-25  |  19KB  |  500 lines
  1.  ****************************************************************************
  2.  
  3.       lispsql.doc
  4.       Copyright (C) 1991-1992 by Autodesk, Inc.
  5.          
  6.       Permission to use, copy, modify, and distribute this software 
  7.       for any purpose and without fee is hereby granted, provided 
  8.       that the above copyright notice appears in all copies and that 
  9.       both that copyright notice and this permission notice appear in 
  10.       all supporting documentation.
  11.  
  12.       THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT EXPRESS OR IMPLIED
  13.       WARRANTY.  ALL IMPLIED WARRANTIES OF FITNESS FOR ANY PARTICULAR
  14.       PURPOSE AND OF MERCHANTABILITY ARE HEREBY DISCLAIMED.
  15.  *****************************************************************************
  16.  
  17.     The AutoLISP-SQL interface is  a number of functions which can be 
  18.     classified as either high or low level. With high-level functions, access 
  19.     to the databases are represented as SQL expressions to be automatically 
  20.     converted to a standard data structure and transferred to the DBMS driver. 
  21.     The low level functions are designed to allow the programmer to generate 
  22.     these required structures manually.
  23.  
  24.     To use the AutoLISP-SQL interface load LISPSQL.EXP with the 'xload' 
  25.     command:
  26.     
  27.     (xload "lispsql")
  28.  
  29.     The general case is that functions return 1 (for TRUE) or nil.
  30.                                                  
  31.     asi_initdrv  - Driver initialization
  32.  
  33.     (asi_initdrv drvname)
  34.  
  35.     This function is used to initialize the connection between the 
  36.     Application Program and the Driver referenced by <drvname>.  The DBMS 
  37.     handle (or driver handle) is allocated by this function.  The driver name 
  38.     <drvname>, specified is the only argument to this function and is the 
  39.     logical name of the driver which is referenced in the ACAD.ASE file.  
  40.     This function returns the unique driver handle number on success. 
  41.     
  42.     For example:
  43.  
  44.     (if (setq drv (asi_initdrv "DBASE4"))
  45.         (prin1 "Driver loaded")
  46.         (prin1 "Can't load driver")
  47.     )
  48.  
  49.     asi_termdrv  - Driver Termination
  50.  
  51.     (asi_termdrv drive)
  52.  
  53.     This function is used to terminate the communication between an
  54.     Application Program and the DBMS Driver specified by its handle. The
  55.     Driver, its connection and communication handles will be freed up.
  56.     This function returns 1, on success.
  57.  
  58.     asi_termsql    -  Terminate ASI interface
  59.  
  60.     (asi_termsql)
  61.     
  62.     This function is used to terminate the ASI interface in this
  63.     Application Program. This function complements the ASI initialization
  64.     function listed above. This function returns 1, on success.
  65.  
  66.     Caution: if this function is used in one LISP-application, any
  67.     other LISP-application, been active in the same time, will be destroyed.
  68.  
  69.      Warning: You must execute this function at the end of your application
  70.      for all the memory to be released.
  71.  
  72.     Interaction with any given database is segmented into seven logical steps.
  73.     These steps allow the programmer to open multiple database handles to 
  74.     control any DBMS.  Therefore allowing access to multiple tables inside
  75.     each DBMS. Only one SQL statement may be active for a single handle.
  76.     These steps are:
  77.  
  78.     -- Connecting to database.
  79.             This is, in effect, the process of logging onto a database.
  80.             Most databases require a connection of some sort be made to the 
  81.             database before processing is allowed to take place.
  82.  
  83.     -- Opening a communication handle.
  84.             Each SQL statement in ASI shall be processed via a communication
  85.             handle. The first step towards execution is the opening of a
  86.             handle to a database. This handle can also be called a 'cursor', 
  87.             although definitions of 'cursor' and 'handle' differ widely, they 
  88.             are currently used interchangeably in this document.
  89.  
  90.     -- Compiling the original SQL statement.
  91.             This step is basically comprised of defining an ASCII SQL string
  92.             which represents the SQL statement to be processed. The step
  93.             of compiling is required to compress the SQL statement into a
  94.             standard structure. It is at this point that a syntax check is
  95.             performed on the request.
  96.  
  97.     -- Execution of the SQL statement.
  98.             The execution stage normally follows compilation. In this stage
  99.             the input and output buffers are defined (if necessary) and the
  100.             compiled statement is executed. The input buffer is essentially 
  101.             a link between program variables and variables in the SQL
  102.             expression. The process of specifying the input buffer is
  103.             called "binding". The output buffer is designed for data storage
  104.             during the fetching of query results. Therefore the output
  105.             buffer can be called a "SELECT buffer". The output buffer can be
  106.             defined just before fetching.
  107.  
  108.     -- Fetching.
  109.             Fetching normally follows the query execution (cursor statement).
  110.             Its purpose is to move row by row along the resulting rows set,
  111.             select the current row, and place it into the output buffer. To
  112.             trace the current position in the resulting rows, set the
  113.             communication handle or cursor.  If the cursor is updatable you 
  114.             can update the current row or delete it.
  115.  
  116.     -- Closing a communication handle.
  117.             Terminates the SQL statement processing for a given handle and 
  118.             frees up the handle.
  119.  
  120.     -- Disconnecting from a database.
  121.             Basically the same as logging off of a database.
  122.  
  123.  
  124.     asi_lon  -  Log on to a database.
  125.  
  126.     (asi_lon dhandle basename username password)
  127.  
  128.     During the connection the connection handle is allocated and initialized. 
  129.     In order to connect to the database you will specify the database name, 
  130.     the user name, and the password as the strings (basename, username, 
  131.     password). In addition, you will specify the driver handle, and the unique 
  132.     number (dhandle) defined by the previously executed asi_initdrv function 
  133.     (i.e. you will define the driver which will execute database access 
  134.     requests).  This function returns the connection handles unique number on
  135.     success. 
  136.     
  137.     For example:
  138.  
  139.     (if (setq con (asi_lon drvnumb "DBSQL" "FRUMKIN" "CREDO"))
  140.         (prin1 "Connected to the database")
  141.         (prin1 "Can't connect to the database")
  142.     )
  143.  
  144.  
  145.     asi_lof  -  Log off of a database.
  146.  
  147.     (asi_lof chandle)
  148.  
  149.     This function is used for database disconnection. Specify the unique 
  150.     number (chandle) of the connection handle, and the defined connection 
  151.     handle will be freed. This function returns 1 on success.
  152.  
  153.  
  154.     asi_ohdl  - Open a Handle to a Database.
  155.  
  156.     (asi_ohdl chandle)
  157.  
  158.     The communication handle will be allocated and opened for the database
  159.     specified by the number of the connection handle (chandle). This function
  160.     returns a unique number for the communication handle, if successful. 
  161.     
  162.     For example:
  163.  
  164.  
  165.     (if (setq com (asi_ohdl con))
  166.         (prin1 "Handle opened")
  167.         (prin1 "Can't open handle")
  168.     )
  169.  
  170.  
  171.     asi_chdl  -  Close Handle to a Database.
  172.  
  173.     (asi_chdl handle)
  174.  
  175.     This function is used for closing and freeing the communication handle
  176.     specified by its number (handle). It highly recommended that the 
  177.     communication buffer be closed, because in some cases database changes 
  178.     may be lost if the handle is not closed. This function returns 1 on 
  179.     success.
  180.  
  181.  
  182.     asi_com   - Compile a specific SQL statement for Processing.
  183.  
  184.     (asi_com handle statement)
  185.  
  186.     This function compiles the SQL statement which is passed as a character 
  187.     string in the second argument. The statement is converted to an internal 
  188.     data structure which is returned in the handle argument.  This handle is 
  189.     represented by a unique number. The Driver is responsible for semantic 
  190.     and security testing of an SQL statement. In the initial string one can 
  191.     indicate program variables (using ':') that will be replaced by references 
  192.     to the host variables during the binding process. 
  193.     
  194.     For example:
  195.  
  196.     (if (asi_com com "SELECT * from table WHERE col1 = :value")
  197.         (prin1 "OK")
  198.     )
  199.  
  200.     here 'com' is a unique number for the communication handle, and ":value" 
  201.     is a variable that must be replaced by a reference to the host variable.
  202.     If a syntax error occurs during compilation of the SQL statement, the  
  203.     up arrow symbol at the error position will be displayed, and an error 
  204.     message will be printed.  This function returns 1 on success.
  205.  
  206.  
  207.     asi_bnd
  208.  
  209.     (asi_bnd handle varname varvalue vartype length)
  210.  
  211.     This function is used for binding host variables into an SQL statement. 
  212.     'varname' is a character string that corresponds to the variable name 
  213.     that comes after the colon in the SQL expression. 'varvalue' is a 
  214.     character string that defines a host variable value. The variable 
  215.     'vartype' is character string which defines the host variable type, and
  216.     can be any of the following values.
  217.  
  218.         "asi_hint"      - int
  219.         "asi_hreal"     - double
  220.         "asi_hchar"     - character string
  221.         "asi_hshort"    - short
  222.         "asi_hlong"     - long
  223.         "asi_hfloat"    - float
  224.  
  225.     'length' is the length of the host variable buffer in bytes.  If a NULL 
  226.     value must be bound, then an empty string "" should be passed as the
  227.     'varvalue' argument.  This function returns 1 on success.
  228.     
  229.     For example:
  230.  
  231.     (if (and 
  232.         (asi_cex hdl "CREATE TABLE table (a1 (INT), a2 (CHAR 20))")
  233.         (asi_com hdl "INSERT INTO table values (:a, :b)")
  234.         (asi_bnd hdl "a" "" "asi_hint" 8)       ; NULL value
  235.         (asi_bnd hdl "b" "text" "asi_hchar" 20) ; 'text' value
  236.         )
  237.         (prin1 "OK")
  238.     )
  239.  
  240.  
  241.     asi_exe - Execute an SQL statement.
  242.  
  243.     (asi_exe hdl)
  244.  
  245.     This function executes the compiled SQL statement. The internal data
  246.     structure is contained in the handle argument, and is represented by its 
  247.     unique number. This function returns 1 on success. 
  248.     
  249.     For example:
  250.  
  251.     (if (and
  252.         (asi_com hdl "CREATE TABLE table (a1 (INT), a2 (CHAR 20))")
  253.         (asi_exe hdl)
  254.         )
  255.         (prin1 "OK")
  256.     )
  257.  
  258.  
  259.     asi_cex - Compile and execute in one step.
  260.  
  261.     (asi_cex hdl statement)
  262.  
  263.     Compilation and execution are combined into one step in asi_cex.  This
  264.     function is used when input buffers are not used. The SQL statement is 
  265.     passed as a character string in the second argument. The statement
  266.     is converted to an internal data structure which is contained in the
  267.     hdl argument and is represented by its unique number.  This function 
  268.     returns 1 on success.
  269.  
  270.  
  271.     asi_fet - Fetching in a forward direction.
  272.  
  273.     (asi_fet com)
  274.  
  275.     This function is used for fetching the result rows set in the
  276.     forward direction. The communication handle number is passed as the 
  277.     only argument. After execution of the query the current position
  278.     in the selection set is just before the first row (-1). The asi_fet
  279.     function moves the cursor one row forward. If the last row was the 
  280.     current row prior to an asi_fet call, the current position will be just
  281.     after it and 'nil' will be return. 
  282.     
  283.     For example:
  284.  
  285.     (while (asi_fet com)  ; cycle by all rows
  286.         .....
  287.     )
  288.  
  289.  
  290.     asi_fbk - Fetch in a Backward Direction.
  291.  
  292.     (asi_fbk com)
  293.  
  294.     This function is used for fetching the result rows set in the backward 
  295.     direction. The communication handle number is passed as the only argument. 
  296.     If the first row was the current row prior to an asi_fbk call then the 
  297.     current position will be just before it (-1) and nil will be return. 
  298.  
  299.  
  300.     asi_ftr - Fetching the first row.
  301.  
  302.     (asi_ftr com)
  303.  
  304.     This function makes the first row of the resulting rows set current.
  305.     The communication handle number is passed as the only argument.
  306.  
  307.  
  308.     asi_fbr - Fetch the last row.
  309.  
  310.     (asi_fbr com)
  311.  
  312.     This function makes the last row of the resulting rows set current.
  313.     The communication handle number is passed as the only argument.
  314.  
  315.  
  316.     asi_del - Delete the current row while fetching.
  317.  
  318.     (asi_del com)
  319.  
  320.     This function is used to delete the current row while fetching the results 
  321.     of a query.  The communication handle number is passed as the only
  322.     argument.  In other words this function fulfills a positioned delete SQL 
  323.     statement.  This function will only be successful if and only if the 
  324.     cursor is updatable (in terms of SQL). This function returns 1 on success.
  325.  
  326.  
  327.     asi_upd - Update the Current Row while Fetching.
  328.  
  329.     (asi_upd com colname value)
  330.  
  331.     This function is used to update the current row while fetching the
  332.     results of a query (Positioned Update).  The communication handle number
  333.     is passed as the first argument (com). 'colname' is a name of a column
  334.     from the table being updated in the form of character string, 'value' is
  335.     the new value which will replace the current value in the column.  The 
  336.     new value is passed in as character string.  If an empty string ("") is 
  337.     passed in the 'value' argument, the current value will be changed to NULL. 
  338.     This function will succeed if and only if the cursor is updatable 
  339.     (in terms of SQL). This function returns 1 on success.
  340.  
  341.  
  342.     asi_cmt  -  Commit a Transaction.
  343.  
  344.     (asi_cmt com)
  345.  
  346.     This function is used to save changes in the database.  It should be
  347.     used after all of the transaction operations have been executed.  This 
  348.     operation will only work if the DBMS supports transactions and can handle 
  349.     the COMMIT statement.  The communication handle number is passed in the 
  350.     'com' argument.  This function returns 1, on success.
  351.  
  352.  
  353.     asi_rbk  -  Roll back a Transaction.
  354.  
  355.     (asi_rbk com)
  356.  
  357.     This function performs a rollback of all of the changes that have not yet
  358.     been committed to the database. This function will only work if the
  359.     database is capable of performing a rollback. In most cases, a rollback 
  360.     is poorly defined by most DBMS's. The communication handle number is 
  361.     passed in the 'com' argument.  This function returns 1, on success.
  362.  
  363.  
  364.     asi_cvl  -  Get a column value from the current row.
  365.  
  366.     (asi_cvl com ncol)
  367.  
  368.     This function can be used to get the results of a query.  On success, 
  369.     this function returns the value of the column specified by its number, 
  370.     'ncol'.  The communication handle number is passed as the first argument 
  371.     'com'.  The empty string ("") corresponds to a NULL value.  Column 
  372.     numbers start from 0.  If the column number exceeds the maximum number 
  373.     of columns, the function will return nil.
  374.  
  375.  
  376.     asi_gettable  - Get the results of a query as a linked list.
  377.  
  378.     (asi_gettable com)
  379.  
  380.     This function is used to get the results of a query, and return it in a 
  381.     linked list form.   The communication handle number is passed in the 
  382.     'com' argument.  This function should be executed after asi_exe (opening 
  383.     a cursor).  If this function is called while the position in the 
  384.     selection set is set before the first row, then only the remaining rows 
  385.     will be returned in the link list.  After running this function, the 
  386.     current position in the resulting set will be set to just after the last 
  387.     string.  On success, this function returns a list which consists of 
  388.     rows value sub lists.  The length of every sub list is equal to the 
  389.     columns number. 
  390.     
  391.     For example
  392.  
  393.     (nth i (nth j (asi_gettable com)))  
  394.  
  395.     returns the value from the j-th row and the i-th column.
  396.  
  397.  
  398.     asi_cds - Get the Description of Query Results.
  399.  
  400.     (asi_cds com column)
  401.  
  402.     This function is used to obtain the full description of all the columns 
  403.     that are available in the resulting set.  It is useful when executing
  404.     the query with the column list undefined.  The column list can be obtained 
  405.     just after compilation or execution of the SQL statement.  The 
  406.     communication handle number is passed in the 'com' argument.  The 'ncol'
  407.     argument specifies the number of the requested column.  The function 
  408.     will return a list of column specifications for the requested column. 
  409.     This list consists of the column name, the precision, and the scale.
  410.  
  411.  
  412.     asi_rowqty  - Get the number of rows in a selection set.
  413.  
  414.     (asi_rowqty com)
  415.  
  416.     On success, this function returns the total number of rows in the 
  417.     resulting selection set as a double value.  The communication handle 
  418.     number is passed in the 'com' argument.
  419.  
  420.     Caution: AutoLISP does not support long integer values.
  421.  
  422.  
  423.     asi_currow  - Get the Current Row Number.
  424.  
  425.     (asi_currow com)
  426.  
  427.     On success, this function returns the current row number of the resulting
  428.     selection set as a double.  The communication handle number is passed in
  429.     the 'com' argument.
  430.  
  431.     Caution: AutoLISP does not support long integer values.
  432.  
  433.  
  434.     asi_synnerpos - Get SQL Syntax error position
  435.  
  436.     (asi_synnerpos com)
  437.  
  438.     This function returns the approximate position of a syntax error that 
  439.     occurred in the original SQL statement, as detected by the asi_com 
  440.     function.  The communication handle number is passed in the 'com' 
  441.     argument.
  442.  
  443.  
  444.     asi_stm - Get Type of the SQL Statement
  445.  
  446.     (asi_stm com)
  447.  
  448.     This function returns the type of SQL statement associated with a
  449.     communication handle.  The 'com' argument specifies the handle number of 
  450.     the SQL statement.  The possible return types are as follows:
  451.  
  452.          "ASI_DELETE"
  453.          "ASI_CREATE"
  454.          "ASI_CURSOR"   cursor operation
  455.          "ASI_GRANT"
  456.          "ASI_REVOKE"
  457.          "ASI_INSERT"
  458.          "ASI_DROP"
  459.          "ASI_UPDATE"
  460.          "ASI_ALTER"
  461.  
  462.  
  463.     asi_opr - Get the Stage of the SQL Statement Processing.
  464.  
  465.     (asi_opr com)
  466.  
  467.     This function returns the stage of the SQL statement associated
  468.     with a communication handle.  The communication handle is passed in the
  469.     'com' argument.  The possible return values are:
  470.  
  471.         "ASI_COM"
  472.         "ASI_EXE"
  473.         "ASI_DEL"
  474.         "ASI_FET"
  475.         "ASI_FBK"
  476.         "ASI_UPD"
  477.         "ASI_CMT"
  478.         "ASI_RBK"
  479.         "ASI_FFR"
  480.         "ASI_FLR"
  481.  
  482.  
  483.     ERROR HANDLING.
  484.  
  485.     ASI functions usually return 1 or nil. If a function returns nil
  486.     and there is no error message, the cursor contains an error code which 
  487.     reflects the type of error that occurred. It is up to the application 
  488.     program to decide what should be done in each case and how to handle
  489.     the situation.
  490.  
  491.     asi_errmsg - Get an Error Message.
  492.  
  493.     (asi_errmsg com)
  494.  
  495.     This function returns the error message associated with a communication 
  496.     handle as a character string.  The communication handle is specified by
  497.     its number in the 'com' argument. 
  498.  
  499.  
  500.